Cream of the Crop 3/Cream of the Crop 3.iso/utility/fsco3712.zip/FSCODE.DOC

Text File | 1994-01-30 | 5KB | 130 lines

   NAME
    FSCode -- Encode a binary file using only ASCII characters (V37)

   SYNOPSIS
    FSCode FILE/A,TO,E=ENCODE/S

   FUNCTION
    FSCode was born to be a more efficient replacement for UUencode; it's
    purpose is to encode a binary file (an executable, for example, or an
    archive such as those made by Zip or LhA) using only the standard
    ASCII character set, i.e. the characters between 32 and 126.

    UUencode encodes 3 bytes into 4 characters, enlarging a file by 33%;
    FSCode does a better job by encoding 4 bytes (a longword) into 5
    characters: the enlargement is only 25%.  This theoretical figure
    does not take into account a couple of control lines and the line
    feeds used to subdivide the resulting file, and two more control
    characters per line needed by UUencode; the real enlargement tends to
    26.6...% for FSCode and to 37.7...% for UUencode.

    It must be made clear that the information contained in the encoded
    files is exactly the same, so if you use UUencode or FSCode to send
    binary files into electronic mail messages, that will be then
    compressed, the size of the resulting packets will be very similar,
    in perfect accordance to the information theory.  The advantage is
    that the readable message stored on your disks will take less space,
    and that you will be able to send bigger files when there is a limit
    on the size of a single message.

    One more advantage of FSCode over UUencode is that it uses a 32-bit
    CRC to check the correctness of the decoded file; one disadvantage is
    that it doesn't use a per-line checksum, so you won't know exactly
    where the file was corrupted.

   INPUTS
    FILE - Input file to encode (if the ENCODE switch is used) or decode.

    TO - Optional output file for the encoded or decoded data.
        If the destination file is omitted, FSCode will send it's output
        to the standard output when encoding, or to the file name
        specified in the encoded file when decoding.

    ENCODE - A switch that instructs FSCode to encode the input file.
        By default FSCode will try to decode an already encoded file and
        reproduce the original data.

   RESULT
    FSCode will output a file that looks like this:

        !start Example
        E4x~n4MPvGMo9KC4L]7:J^.a,N5B2E###*4
        !end 25 4E9AB940

    The first line contains the file name, without drive/directory
    specifications.  This is to prevent both errors when trying to decode
    a file produced on a system different than yours and funny things
    like overwriting system files.  The decoding process actually uses
    the complete file name, without removing the drive/directory part
    that might have been added after the encoding:  this is to ease the
    creation of scripts and such things for automatic decoding.

    The last line contains the size (in decimal) and the 32-bit CRC (in
    hexadecimal) of the original file.

    Should FSCode fail for any reason, an (hopefully) meaningful message
    will be printed on your screen.  Examples include `No start line' or
    `CRC mismatch' or `Can't open file <file name>'.

   NOTES
    FSCode is absolutely tolerant on what you do to the encoded lines,
    provided that you do not add or remove characters in the range from
    33 to 126 [!-~].  You can reflow the lines and insert spaces, line
    feeds or other control characters freely.

    The absence of the !end line does not influence the correctness of
    the decoded file.  Of course you miss the size and CRC check, but
    otherwise the decoding process is not influenced.

    For a deeper description of the encoding algorithm, see the file
    `Specs.Doc' and the source code.

   NOTES ON THE SOURCE CODE
    The included source code is completely in C, but the executable is
    really made from assembly source generated from the compiler output
    and optimized by hand, which improves encoding speed by about 15%.

    I won't spread the assembly source because I'm not very comfortable
    at working on it (particularly when it's debugging time), so I prefer
    to make improvements on the C source and then propagate them to the
    assembly version after they have been tested; it is obvious that
    distributing the assembly source would break this process.

   DISTRIBUTION
    This program is freeware.  You may redistribute it as long as:
     - this text and the source code are included;
     - you don't charge more than a nominal copying fee for distribution.

    Please state your modifications to the code with a clear comment, and
    send me your modified version.  It would be a good idea to include
    the original code, anyway.

    Any contribution will be greatly appreciated (I'm a poor engineering
    student, you know).

   DISCLAIMER
    The author does not assume any responsibility for damages which could
    result by the use of this program.  The entire risk for the use of
    this program is assumed by the user.

   AUTHOR
    Flavio Stanchina
    Loc. Montevaccino, 39
    38040 Trento (Italia)

    email: 2:333/[e-mail]

   ACKNOWLEDGEMENTS
    Thanks to Gian Maria Calzolari (2:332/[e-mail]) for beta
    testing and suggestions, and for writing a new ExtractFile.ems ARexx
    script for EMS that supports both UUencode and FSCode.

    Thanks to Marco Amadori (2:333/[e-mail]) for beta testing.

    Thanks to Sandro Tolaini (2:332/[e-mail]) for a bug report.

    And finally thanks to all the participants of the AMIGA.ITA Fidonet
    conference for suggestions and encouragement.